<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
<!-- creator-vcs.qdoc -->
  <title>Using Version Control Systems | Qt Creator Manual</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="index.html">Qt Creator Manual</a></td><td >Using Version Control Systems</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right"><a href="index.html">Qt Creator Manual 4.11.1</a></td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
  <link rel="prev" href="creator-project-wizards-xml.html" />
  <link rel="next" href="creator-vcs-bazaar.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="creator-project-wizards-xml.html">Adding XML-Based Wizards</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-vcs-bazaar.html">Using Bazaar</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#setting-up-version-control-systems">Setting Up Version Control Systems</a></li>
<li class="level1"><a href="#setting-up-general-options">Setting Up General Options</a></li>
<li class="level1"><a href="#creating-vcs-repositories-for-new-projects">Creating VCS Repositories for New Projects</a></li>
<li class="level1"><a href="#using-common-functions">Using Common Functions</a></li>
<li class="level2"><a href="#adding-files">Adding Files</a></li>
<li class="level2"><a href="#viewing-diff-output">Viewing Diff Output</a></li>
<li class="level2"><a href="#viewing-versioning-history-and-change-details">Viewing Versioning History and Change Details</a></li>
<li class="level2"><a href="#annotating-files">Annotating Files</a></li>
<li class="level2"><a href="#committing-changes">Committing Changes</a></li>
<li class="level2"><a href="#reverting-changes">Reverting Changes</a></li>
<li class="level2"><a href="#viewing-status">Viewing Status</a></li>
<li class="level2"><a href="#updating-the-working-tree">Updating the Working Tree</a></li>
<li class="level2"><a href="#deleting-files">Deleting Files</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Using Version Control Systems</h1>
<span class="subtitle"></span>
<!-- $$$creator-version-control.html-description -->
<div class="descr"> <a name="details"></a>
<p>Version control systems supported by Qt Creator are:</p>
<div class="table"><table class="generic">
 <thead><tr class="qt-style"><th >Version Control System</th><th >Address</th><th >Notes</th></tr></thead>
<tr valign="top" class="odd"><td ><a href="creator-vcs-bazaar.html">Bazaar</a></td><td ><a href="http://bazaar.canonical.com/">http://bazaar.canonical.com/</a></td><td ></td></tr>
<tr valign="top" class="even"><td ><a href="creator-vcs-clearcase.html">ClearCase</a></td><td ><a href="http://www-01.ibm.com/software/awdtools/clearcase/">http://www-01.ibm.com/software/awdtools/clearcase/</a></td><td >Disabled by default. To enable the plugin, select <b>Help</b> &gt; <b>About Plugins</b> &gt; <b>Version Control</b> &gt; <b>ClearCase</b>, and then restart Qt Creator.</td></tr>
<tr valign="top" class="odd"><td ><a href="creator-vcs-cvs.html">CVS</a></td><td ><a href="http://www.nongnu.org/cvs/">http://www.nongnu.org/cvs/</a></td><td ></td></tr>
<tr valign="top" class="even"><td ><a href="creator-vcs-git.html">Git</a></td><td ><a href="http://git-scm.com/">http://git-scm.com/</a></td><td >Git version 1.9&#x2e;0, or later<p>Gerrit version 2.6, or later</p>
</td></tr>
<tr valign="top" class="odd"><td ><a href="creator-vcs-mercurial.html">Mercurial</a></td><td ><a href="http://mercurial.selenic.com/">http://mercurial.selenic.com/</a></td><td ></td></tr>
<tr valign="top" class="even"><td ><a href="creator-vcs-perforce.html">Perforce</a></td><td ><a href="http://www.perforce.com">http://www.perforce.com</a></td><td >Server version 2006.1 and later<p>Disabled by default. To enable the plugin, select <b>Help</b> &gt; <b>About Plugins</b> &gt; <b>Version Control</b> &gt; <b>Perforce</b>, and then restart Qt Creator.</p>
</td></tr>
<tr valign="top" class="odd"><td ><a href="creator-vcs-subversion.html">Subversion</a></td><td ><a href="http://subversion.apache.org/">http://subversion.apache.org/</a></td><td >Subversion version 1.7&#x2e;0 and later</td></tr>
</table></div>
<a name="setting-up-version-control-systems"></a>
<h2 id="setting-up-version-control-systems">Setting Up Version Control Systems</h2>
<p>Qt Creator uses the version control system's command line clients to access your repositories. To allow access, make sure that the command line clients can be located using the <code>PATH</code> environment variable. Alternatively, specify the path to the command line client executable in the <b>Command</b> field in the version control system specific tab in <b>Tools</b> &gt; <b>Options</b> &gt; <b>Version Control</b>.</p>
<p>If authentication is required to access the repository, enter the user credentials in the <b>Username</b> and <b>Password</b> fields.</p>
<p>Enter a timeout for version control operations in the <b>Timeout</b> field.</p>
<p>For some version control systems, you can specify the maximum number of lines the log can contain in the <b>Log count</b> field.</p>
<p>After you set up the version control system, use the command line to check that everything works (for example, use the status command). If no issues arise, you should be ready to use the system also from Qt Creator.</p>
<p>For more information on using Git for Windows, see <a href="creator-vcs-git.html#using-git-for-windows">Using Git for Windows</a>.</p>
<a name="setting-up-general-options"></a>
<h2 id="setting-up-general-options">Setting Up General Options</h2>
<p>Select <b>Tools</b> &gt; <b>Options</b> &gt; <b>Version Control</b> &gt; <b>General</b> to specify settings for submit messages:</p>
<ul>
<li><b>Wrap submit messages at</b> limits the line length of a submit message to the specified number of characters.</li>
<li><b>Submit message check script</b> is a script or program that can be used to perform checks on the submit message before submitting. The submit message is passed in as the script's first parameter. If there is an error, the script should output a message on standard error and return a non-zero exit code.</li>
<li><b>User/alias configuration file</b> is a text file that lists author names in mailmap format. For each author, you must specify a real name and email address and optionally an alias and a second email address. For example:<pre class="cpp">

  Jon Doe <span class="operator">&lt;</span>Jon<span class="operator">.</span>Doe@company<span class="operator">.</span>com<span class="operator">&gt;</span> jdoe <span class="operator">&lt;</span>jdoe@somemail<span class="operator">.</span>com<span class="operator">&gt;</span>
  Hans Mustermann <span class="operator">&lt;</span>Hans<span class="operator">.</span>Mustermann@company<span class="operator">.</span>com<span class="operator">&gt;</span> hm <span class="operator">&lt;</span>info@company<span class="operator">.</span>com<span class="operator">&gt;</span>

</pre>
<p>After you specify a file in this field, you can select authors as values of the submit message fields in the <b>Nicknames</b> dialog.</p>
</li>
<li><b>User fields configuration file</b> is a simple text file consisting of lines specifying submit message fields that take authors as values, for example:<pre class="cpp">

  Acked<span class="operator">-</span>by:
  Initial<span class="operator">-</span>patch<span class="operator">-</span>by:
  Reported<span class="operator">-</span>by:
  Rubber<span class="operator">-</span>stamped<span class="operator">-</span>by:
  Signed<span class="operator">-</span>off<span class="operator">-</span>by:
  Tested<span class="operator">-</span>by:

</pre>
<p>After you specify a file in this field, you can add authors as values of the submit message fields when submitting changes. If you also specified a <b>User/alias configuration file</b>, you can select authors in the <b>Nicknames</b> dialog.</p>
</li>
<li><b>SSH prompt command</b> specifies an ssh-askpass command that you can use (on Linux) to prompt the user for a password when using SSH. For example, <code>ssh-askpass</code> or <code>x11-ssh-askpass</code>, depending on the ssh-askpass implementation that you use.</li>
<li><b>Reset VCS Cache</b> resets the version control system configuration to a state known to Qt Creator after it has been changed from the command line, for example.</li>
</ul>
<a name="creating-vcs-repositories-for-new-projects"></a>
<h2 id="creating-vcs-repositories-for-new-projects">Creating VCS Repositories for New Projects</h2>
<p>Qt Creator allows you to create repositories for version control systems that support local repository creation, such as Git, Mercurial, or Bazaar. When creating a new project by selecting <b>File</b> &gt; <b>New File or Project</b>, you can choose a version control system on the final wizard page.</p>
<p>You can also select <b>Tools</b> and then select <b>Create Repository</b> in the submenu for the version control system.</p>
<p>To import a project that is under version control, choose <b>File &gt; New File or Project &gt; Project from Version Control</b> and select the version control system that you use. Follow the instructions of the wizard to import the project.</p>
<a name="using-common-functions"></a>
<h2 id="using-common-functions">Using Common Functions</h2>
<p>The <b>Tools</b> menu contains a submenu for each supported version control system. This section describes using the functions that are available for all the supported version control systems. For more information about the additional functions and options available for a particular version control system, see:</p>
<ul>
<li><a href="creator-vcs-bazaar.html">Using Bazaar</a></li>
<li><a href="creator-vcs-clearcase.html">Using ClearCase</a></li>
<li><a href="creator-vcs-cvs.html">Using CVS</a></li>
<li><a href="creator-vcs-git.html">Using Git</a></li>
<li><a href="creator-vcs-mercurial.html">Using Mercurial</a></li>
<li><a href="creator-vcs-perforce.html">Using Perforce</a></li>
<li><a href="creator-vcs-subversion.html">Using Subversion</a></li>
</ul>
<p>The <b>Version Control</b> output pane displays the commands that are executed, a timestamp, and the relevant output. Select <b>Window &gt; Output Panes &gt; Version Control</b> to open the pane.</p>
<p class="centerAlign"><img src="images/qtcreator-vcs-pane.png" alt="" /></p><a name="adding-files"></a>
<h3 id="adding-files">Adding Files</h3>
<p>When you create a new file or a new project, the wizard displays a page asking whether the files should be added to a version control system. This happens when the parent directory or the project is already under version control and the system supports the concept of adding files, for example, Perforce and Subversion. Alternatively, you can add files later by using the version control tool menus.</p>
<a name="viewing-diff-output"></a>
<h3 id="viewing-diff-output">Viewing Diff Output</h3>
<p>All version control systems provide menu options to <i>diff</i> the current file or project: to compare it with the latest version stored in the repository and to display the differences. In Qt Creator, a diff is displayed in a read-only editor. If the file is accessible, you can double-click on a selected diff chunk and Qt Creator opens an editor displaying the file, scrolled to the line in question.</p>
<p class="centerAlign"><img src="images/qtcreator-vcs-diff.png" alt="" /></p><p>With Git, Mercurial, and Subversion, the diff is displayed side-by-side in a <a href="creator-diff-editor.html">diff editor</a> by default. To use the inline diff view instead, select the <b>Switch to Text Diff Editor</b> (1) option from the toolbar. In the inline diff view, you can use context menu commands to apply, revert, stage, and unstage hunks, as well as send them to a code pasting service.</p>
<a name="viewing-versioning-history-and-change-details"></a>
<h3 id="viewing-versioning-history-and-change-details">Viewing Versioning History and Change Details</h3>
<p>Display the versioning history of a file by selecting <b>Log</b> or <b>Filelog</b>. Typically, the log output contains the date, the commit message, and a change or revision identifier.</p>
<a name="annotating-files"></a>
<h3 id="annotating-files">Annotating Files</h3>
<p>Annotation views are obtained by selecting <b>Annotate</b> or <b>Blame</b>. Selecting <b>Annotate</b> or <b>Blame</b> displays the lines of the file prepended by the change identifier they originate from. Clicking on the change identifier shows a detailed description of the change.</p>
<p>To show the annotation of a previous version, right-click on the version identifier at the beginning of a line and choose one of the revisions shown at the bottom of the context menu. This allows you to navigate through the history of the file and obtain previous versions of it. It also works for Git and Mercurial using SHA-1.</p>
<p>The same context menu is available when right-clicking on a version identifier in the file log view of a single file.</p>
<a name="committing-changes"></a>
<h3 id="committing-changes">Committing Changes</h3>
<p>Once you have finished making changes, submit them to the version control system by choosing <b>Commit</b> or <b>Submit</b>. Qt Creator displays a commit page containing a text editor where you can enter your commit message and a checkable list of modified files to be included.</p>
<a name="reverting-changes"></a>
<h3 id="reverting-changes">Reverting Changes</h3>
<p>All supported version control systems support reverting your project to known states. This functionality is generally called <i>reverting</i>.</p>
<p>The changes discarded depend on the version control system.</p>
<p>A version control system can replace the <b>Revert</b> menu option with other options.</p>
<a name="viewing-status"></a>
<h3 id="viewing-status">Viewing Status</h3>
<p>You can select <b>Status</b> to view the status of the project or repository.</p>
<a name="updating-the-working-tree"></a>
<h3 id="updating-the-working-tree">Updating the Working Tree</h3>
<p>You can select <b>Update</b> to update your working tree with the latest changes from the branch. Some version control systems allow you to choose between updating the current project and updating all projects.</p>
<a name="deleting-files"></a>
<h3 id="deleting-files">Deleting Files</h3>
<p>You can select <b>Delete</b> to delete obsolete files from the repository.</p>
</div>
<!-- @@@creator-version-control.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="creator-project-wizards-xml.html">Adding XML-Based Wizards</a>
<span class="naviSeparator">  &#9702;  </span>
<a class="nextPage" href="creator-vcs-bazaar.html">Using Bazaar</a>
</p>
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
